Each track record contains the following fields:
1) Track id: used for referencing tracks.
2) Track file: filename of the track.
3) Track flags: see header_music.py for a list of available flags.
4) Continue Track flags: Shows in which situations or cultures the track can continue playing. See header_music.py for a list of available flags.
The file module_music.py is where the music tracks of the module are getting recorded and defined. The file simply consists of a list of tuples. Observe:
("ambushed_by_vaegir", "ambushed_by_vaegir.ogg", mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege, mtf_sit_fight|mtf_sit_multiplayer_fight|mtf_culture_all),
This is a standard music track called "ambushed by vaegir" which gets played when the player gets ambushed under certain circumstances. Lets do a short tuple examination:
"ambushed_by_vaegir"
The name of the track as known by the code. You can reference to it at other places in the Module System with track_ambushed_by_vaegir.
"ambushed_by_vaegir.ogg"
The name of the physical music file. If mtf_module_track is present in the third field, the file is in (module direction)/Music. Otherwise it is a Native file in (M&B direction)/Music. The first mistake which you will probably make is to forget to put the mtf_module_track flag when adding your own track.
mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege
The play conditions, so when the track will play: in what situation and in what culture? In our example here: The track will play only if the culture is 2 (Vaegir) AND the situation is either Ambush OR Siege. Not having culture flags is the same as putting mtf_culture_all (will match all cultures) - this may be confusing, but this is what M&B does.
mtf_sit_fight|mtf_sit_multiplayer_fight|mtf_culture_all),
The continue condition, so whether the track continues to play when the situation and/or culture changes (otherwise it will fade out). In our example here: The track will continue to play in any culture AND if the situation is Ambush OR Siege OR Fight. The track will also continue to play at the multiplayer. Note that the start play conditions are automatically added to continue play conditions (and it makes sense to do so - see process_music.py if you are curious). Usually you will ignore it (stick with the culture in the play condition) or put mtf_culture_all (when you want maximum chance of continuing play - if your play field has no mtf_culture_x, this is implied and can be omitted).
The following music track flags are available for use (describing their Native behaviour):
| mtf_culture_1 | lets the music play if the culture is culture 1 (Swadia). |
| mtf_culture_2 | lets the music play if the culture is culture 2 (Vaegirs). |
| mtf_culture_3 | lets the music play if the culture is culture 3 (Khergits). |
| mtf_culture_4 | lets the music play if the culture is culture 4 (Nords). |
| mtf_culture_5 | lets the music play if the culture is culture 5 (Rhodoks). |
| mtf_culture_6 | lets the music play if the culture is culture 6 (Sarranids). |
| mtf_culture_all | will allow the music to continue playing at any culture which handles the case when the player is hopping across the invisible border regularly.[1] |
| mtf_looping | loops the track until continue conditions are not met (anymore). |
| mtf_module_track | must be added to custom tracks for the mod located in the music folder at the module directory. |
| mtf_persist_until_finished | plays the track until finished and nothing can stop it. Use with care! |
| mtf_sit_ambient_music | sets the music preference to have an ambient setting. This flag has been introduced with VC and needs first to be added to header_music.py if using the Native MS (mtf_sit_ambient_music = 0x02000000). A simple plugin and use of this flag is not possible, look up its usage at the VC MS. |
| mtf_sit_ambushed | sets the music situation when an ambush is happening or if the odds against the player in a battle are worse than 2:1. |
| mtf_sit_arena | sets the music situation when the player enters an arena, joins a tournament or duels with a lord. |
| mtf_sit_day | sets the music situation when it is daytime at the world map (not used in Native). |
| mtf_sit_encounter_hostile | is not really getting used in Native, the track encounter_hostile_nords.ogg never plays. |
| mtf_sit_feast | sets the music situation when a feast is going on in a lords hall which gets visited. |
| mtf_sit_fight | sets the music sitation when a battle goes on. |
| mtf_sit_killed | sets the music situation if the player got defeated in battle or is retreating. |
| mtf_sit_main_title | sets the music at the main menu. |
| mtf_sit_multiplayer_fight | sets the music at the multiplayer.[2] |
| mtf_sit_night | sets the music situation when it is nighttime at the world map. |
| mtf_sit_siege | sets the music situation when a siege is going on. |
| mtf_sit_tavern | sets the music situation when visiting a tavern. |
| mtf_sit_town | sets the music situation when visiting a town. |
| mtf_sit_town_infiltrate | sets the music situation when infiltrating a town. |
| mtf_sit_travel | sets the music situation when traveling on the world map. |
| mtf_sit_victorious | sets the music situation if the player is victorius in battle. |
| mtf_start_immediately | removes the delays between tracks and overrides song priority.[3] |
Be aware that you can edit the usage of the already existing situation flags, they are not hard-coded (with the great exception of mtf_sit_main_title. There are 16 defined defined music situations in header_music.py but you can implement up to three more with the unused values between the mtf_sit_feast and mtf_module_track constants.[4] The flag mtf_sit_ambient_music is a prime example for this.
There are six defined cultures (mtf_culture_1 to mtf_culture_6) with mtf_culture_all denoting all of them. As mentioned above, setting no culture flags is the same as putting mtf_culture_all. In original Vanilla M&B the sixth culture is used to denote a neutral faction, but is actually used for various bandits in the code. In Warband the sixth culture is used for Sarranids and, interestingly enough, still for various bandits. Note that in Native the player's party culture is 0, until he becomes a vassal. Examples for the usage of culture flags:
("ambushed_by_neutral", "ambushed_by_neutral.ogg", mtf_sit_ambushed|mtf_sit_siege, mtf_sit_fight),
This track Will play and continue in all cultures, mtf_culture_all is implied due to no culture flag being set.
("ambushed_by_neutral", "ambushed_by_neutral.ogg", mtf_culture_1|mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege, mtf_culture_4|mtf_sit_fight)
This track will start playing for the cultures 1 and 2, and will continue playing for cultures 1, 2 and 4 (i.e. will fade out in cultures 3, 5 and 6).
Take note that it is not possible to add new culture music flags like mtf_culture_7 as those six flags are hard-coded in the game engine. You can however control the music with operations (the ones affecting the music tracks are play_track, play_cue_track, music_set_situation, music_set_culture) and thus override the default music system to have it be based on some other in-game variable than the culture flags.[5]
Besides the vanilla setup, you may use the fact that Warband is picking music tracks based on the current culture/situation combination. Nothing prevents you from treating those cultures and situations as just abstract numbers. And instead of six cultures and 19 situations - remember, three more can be added to the 16 Native ones - you get 6*19 = 114 unique situations. Actually less as some situations are quite specific (for example mtf_sit_main_title) but you can still get a respectable number to create the needed variety.[4]
Most of the code in the game changes the music through the script music_set_situation_with_culture. For scripters, it is a wrapper for music_set_situation and music_set_culture. For everybody else, it analyzes a situation (see mtf_sit_x flags) and finds one or a variety of cultures appropriate to the situation. Multiple cultures will cause more matches found among the tracks, which will either add to the variety of music or confuse the player with seeming randomness. It is a thin line between both. This script only implictly plays music, the M&B internal music system detects changes in situation and culture and does the actual playing.
Examples of situations and cultures:
Some common music situations (mtf_sit_x) as set in the code are Town menu (travel), Town streets (travel, Warband: town or night), Streets night (travel), Tavern (tavern), Arena Master (travel), Arena melee (arena), Village walk (travel), Castle menu (travel) and Castle hall (travel).
Battles are special as they use triggers to play music. The common battle trigger fires every 30 seconds and sets the situation to mtf_sit_fight or mtf_sit_ambushed if the odds against the player are worse than 2:1. Siege battles start with common siege music, then play battle music as normal.
The world map has a trigger that fires every game hour and tries to play travel music which sets the situation to mtf_sit_travel.
There are also some exceptions since some tracks are explicitely played from scripts, so they don't need any flags. Examples are for example the Native music tracks captured, empty_village, escape, victorious_evil and (only in Warband) wedding.
You may want to have special tracks for every possible situation in the game - resist the urge! From a player point of view more varied travel and battle tracks may bring better value.
When deciding which tracks can continue where (continue condition flags) think in terms of what the average player is likely to do - if he spends only a few seconds in your taverns, maybe you could allow the travel or town or lord's hall music to continue there, so you will not change your music every few seconds; if your taverns are more interesting to hang out, do not allow anything to play there except tavern music.
Try to use mtf_persist_until_finished on shorter tracks only (like Native's victory tracks). However, if you want to annoy the player, maybe because he is a cheater, a pirate or you are just plain evil, set these flags:
("punish_player", "punish_player.ogg", mtf_looping|mtf_persist_until_finished|mtf_module_track, 0)
The track will loop forever and cannot be stopped until the player quits the game.
If you want to let any current music fade out, use music_set_situation, 0). The new music will start playing when the situation is set again. Use the play_track operation when you want to play a specific music track and don't want to allow M&B to choose one randomly. Watch out for the continue flags or your music track may stop short. You can use the operation play_cue_track to play a music track over any already playing track. However, there couldn't be thought of a good use for this yet.
The simplest way to play a music track only for a specific encounter (e.g. a zombie horde) is done in following steps:
(try_begin),
(eq, "$g_encountered_party_template","pt_zombie_horde"),
(play_track, "track_zombie_horde", 1),
(try_end),
("zombie_horde", "zombie_horde.ogg", mtf_module_track, mtf_sit_fight|mtf_sit_ambushed|mtf_sit_travel|mtf_culture_all),
As mentioned above in the section about the music track flags, you can add up to three more situation flags to the Native ones. The flag mtf_sit_ambient_music was already mentioned as a prime example for how one got added by the developers of VC. There was also a Native situation flag which got removed out of unknown reasons but for which you can still find remnants in the code. So for reimplementing lord's hall (castle and town castle hall) music you will need to follow these easy steps:
mtf_sit_lords_hall = 0x02000000
# (call_script, "script_music_set_situation_with_culture", mtf_sit_lords_hall),
(this_or_next|eq, ":situation", mtf_sit_town_infiltrate),
(this_or_next|eq, ":situation", mtf_sit_lords_hall), <<<---
(eq, ":situation", mtf_sit_encounter_hostile),
("lords_hall_swadian", "lords_hall_swadian.ogg", mtf_module_track|mtf_culture_1|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_vaegir", "lords_hall_vaegir.ogg", mtf_module_track|mtf_culture_2|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_khergit", "lords_hall_khergit.ogg", mtf_module_track|mtf_culture_3|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_nord", "lords_hall_nord.ogg", mtf_module_track|mtf_culture_4|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_rhodok", "lords_hall_rhodok.ogg", mtf_module_track|mtf_culture_5|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_sarranid", "lords_hall_sarranid.ogg", mtf_module_track|mtf_culture_6|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
At music the file format seems to be not as important as at the sounds. You can use OGG, MP3 and WAV files as music tracks. The developers used the format OGG Vorbis because is free to use and doesn't include any patents.[8] OGG Vorbis is a patent-free container with even better quality than the costly MP3 and the game fully understands it.[9] This file format has a backdraw at sounds which is why you should read also the section about the optimal sound file format! However, testing indicates that music files can remain OGG; they are supposed to be in a streaming format and changing them to WAV is probably not a good idea.[10] Make sure your tracks are stereo, mono tracks might have some problems playing properly.